<html>
<head><meta charset="utf-8"><title>Doc comments on nested items · t-compiler · Zulip Chat Archive</title></head>
<h2>Stream: <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/index.html">t-compiler</a></h2>
<h3>Topic: <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/Doc.20comments.20on.20nested.20items.html">Doc comments on nested items</a></h3>

<hr>

<base href="https://rust-lang.zulipchat.com">

<head><link href="https://rust-lang.github.io/zulip_archive/style.css" rel="stylesheet"></head>

<a name="214317449"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/Doc%20comments%20on%20nested%20items/near/214317449" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Aaron Hill <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/Doc.20comments.20on.20nested.20items.html#214317449">(Oct 23 2020 at 14:06)</a>:</h4>
<p>When working on improving support for custom attributes on statements, I discovered that the <code>unused_doc_comments</code> lint is currently not firing for inner items.</p>
<p>For example, <a href="https://github.com/rust-lang/rust/blob/07a63e6d1fabf3560e8e1e17c1d56b10a06152d9/library/core/src/ptr/mod.rs#L1148-L1157">https://github.com/rust-lang/rust/blob/07a63e6d1fabf3560e8e1e17c1d56b10a06152d9/library/core/src/ptr/mod.rs#L1148-L1157</a></p>
<p>This is due to the way that we handle attributes on statements internally, and will be fixed by my branch.</p>
<p>However, I'm not sure if we want to start linting things like:</p>
<div class="codehilite" data-code-language="Rust"><pre><span></span><code><span class="k">fn</span> <span class="nf">outer</span><span class="p">()</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">    </span><span class="sd">/// My doc comment</span>
<span class="w">    </span><span class="k">fn</span> <span class="nf">some_inner_fn</span><span class="p">()</span><span class="w"> </span><span class="p">{}</span><span class="w"></span>
<span class="p">}</span><span class="w"></span>
</code></pre></div>

<p>One one hand, the lint description is 'rustdoc does not generate documentation for X', which certainly applies in this case. However, this feels different from writing a doc comment on, for exampe, a 'let' statement:</p>
<div class="codehilite" data-code-language="Rust"><pre><span></span><code><span class="sd">/// This comment does nothing</span>
<span class="kd">let</span><span class="w"> </span><span class="n">a</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">25</span><span class="p">;</span><span class="w"></span>
</code></pre></div>

<p>Even if a doc comment on a nested item isn't rendered, it can still trigger formatting by an IDE. It also allows keeping the same style of comments across all functions, which seems nice for consistency.</p>



<a name="214319055"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/Doc%20comments%20on%20nested%20items/near/214319055" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Joshua Nelson <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/Doc.20comments.20on.20nested.20items.html#214319055">(Oct 23 2020 at 14:19)</a>:</h4>
<p>that seems like something I would handle with an <code>allow(unused_doc_comments)</code> IMO</p>



<a name="214319068"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/Doc%20comments%20on%20nested%20items/near/214319068" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Joshua Nelson <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/Doc.20comments.20on.20nested.20items.html#214319068">(Oct 23 2020 at 14:19)</a>:</h4>
<p>rustdoc should warn if documentation is being ignored</p>



<a name="214332638"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/Doc%20comments%20on%20nested%20items/near/214332638" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Aaron Hill <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/Doc.20comments.20on.20nested.20items.html#214332638">(Oct 23 2020 at 16:09)</a>:</h4>
<p><span class="user-mention" data-user-id="232545">@Joshua Nelson</span> Do you think it would make sense to convert those to normal comments?</p>



<a name="214332653"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/Doc%20comments%20on%20nested%20items/near/214332653" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Joshua Nelson <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/Doc.20comments.20on.20nested.20items.html#214332653">(Oct 23 2020 at 16:10)</a>:</h4>
<p>Yes, I think so</p>



<a name="214332725"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/Doc%20comments%20on%20nested%20items/near/214332725" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Joshua Nelson <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/Doc.20comments.20on.20nested.20items.html#214332725">(Oct 23 2020 at 16:10)</a>:</h4>
<p>but you said you liked the symmetry with doc-comments</p>



<a name="214332746"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/Doc%20comments%20on%20nested%20items/near/214332746" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Aaron Hill <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/Doc.20comments.20on.20nested.20items.html#214332746">(Oct 23 2020 at 16:10)</a>:</h4>
<p>I don't have a strong opinon on it</p>



<a name="214332781"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/Doc%20comments%20on%20nested%20items/near/214332781" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Aaron Hill <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/Doc.20comments.20on.20nested.20items.html#214332781">(Oct 23 2020 at 16:10)</a>:</h4>
<p>my branch found several cases of it in the stdlib, so I thought it would be good to come up with an overall policy</p>



<a name="214332923"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/Doc%20comments%20on%20nested%20items/near/214332923" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Joshua Nelson <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/Doc.20comments.20on.20nested.20items.html#214332923">(Oct 23 2020 at 16:12)</a>:</h4>
<p>this seems like a t-libs question IMO, but my opinion is that the rustdoc behavior of warning on the comments is correct</p>



<a name="214332933"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/Doc%20comments%20on%20nested%20items/near/214332933" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Aaron Hill <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/Doc.20comments.20on.20nested.20items.html#214332933">(Oct 23 2020 at 16:12)</a>:</h4>
<p>As a side note, applying <code>#[allow(unused_doc_comments)]</code> doesn't work the way you might initially expect</p>



<a name="214332946"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/Doc%20comments%20on%20nested%20items/near/214332946" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Aaron Hill <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/Doc.20comments.20on.20nested.20items.html#214332946">(Oct 23 2020 at 16:12)</a>:</h4>
<p>applying it to a function affects things <em>inside</em> the function</p>



<a name="214332963"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/Doc%20comments%20on%20nested%20items/near/214332963" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Aaron Hill <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/Doc.20comments.20on.20nested.20items.html#214332963">(Oct 23 2020 at 16:12)</a>:</h4>
<p>it doesn't affect doc comments on the function itself, since you can't have attributes on attributes</p>



<a name="214332986"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/Doc%20comments%20on%20nested%20items/near/214332986" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Joshua Nelson <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/Doc.20comments.20on.20nested.20items.html#214332986">(Oct 23 2020 at 16:12)</a>:</h4>
<p>oh that is confusing :/</p>



<a name="214333019"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/Doc%20comments%20on%20nested%20items/near/214333019" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Aaron Hill <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/Doc.20comments.20on.20nested.20items.html#214333019">(Oct 23 2020 at 16:13)</a>:</h4>
<p>e.g.</p>
<div class="codehilite" data-code-language="Rust"><pre><span></span><code><span class="cp">#[allow(unused_doc_comments)]</span><span class="w"></span>
<span class="sd">/// This is a doc comment</span>
<span class="k">fn</span> <span class="nf">foo</span><span class="p">()</span><span class="w"> </span><span class="p">{}</span><span class="w"></span>
</code></pre></div>

<p>will still warn on the doc comment</p>



<a name="214333055"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/Doc%20comments%20on%20nested%20items/near/214333055" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Joshua Nelson <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/Doc.20comments.20on.20nested.20items.html#214333055">(Oct 23 2020 at 16:13)</a>:</h4>
<p>does it make sense to fix that? I would expect it to apply to both the function and the attributes on the function</p>



<a name="214333227"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/Doc%20comments%20on%20nested%20items/near/214333227" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Aaron Hill <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/Doc.20comments.20on.20nested.20items.html#214333227">(Oct 23 2020 at 16:14)</a>:</h4>
<p>I think that would make sense - I think that's what users will expect. However, it does introduce something that looks sort of like 'attributes on attributes', so I think it would need an FCP</p>



<a name="214333294"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/Doc%20comments%20on%20nested%20items/near/214333294" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Joshua Nelson <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/Doc.20comments.20on.20nested.20items.html#214333294">(Oct 23 2020 at 16:15)</a>:</h4>
<p>cc <span class="user-mention" data-user-id="123856">@Vadim Petrochenkov</span></p>



<a name="214333461"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/Doc%20comments%20on%20nested%20items/near/214333461" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Aaron Hill <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/Doc.20comments.20on.20nested.20items.html#214333461">(Oct 23 2020 at 16:16)</a>:</h4>
<p>the downside is that it makes <code>unused_doc_comments</code> special w.r.t to how lint level scoping works</p>



<a name="214333477"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/Doc%20comments%20on%20nested%20items/near/214333477" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Aaron Hill <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/Doc.20comments.20on.20nested.20items.html#214333477">(Oct 23 2020 at 16:16)</a>:</h4>
<p>I don't know how much complexity that will introduce into the linting infrastructure</p>



<a name="214333545"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/Doc%20comments%20on%20nested%20items/near/214333545" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Aaron Hill <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/Doc.20comments.20on.20nested.20items.html#214333545">(Oct 23 2020 at 16:17)</a>:</h4>
<p>if we decide to keep the current behavior, I think we should add a note to 'unused_doc_comments' warnings when there's a <code>#[allow(unused_doc_comments)]</code> that doesn't actually apply</p>



<a name="214333641"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/Doc%20comments%20on%20nested%20items/near/214333641" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Aaron Hill <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/Doc.20comments.20on.20nested.20items.html#214333641">(Oct 23 2020 at 16:18)</a>:</h4>
<p>Since</p>
<div class="codehilite" data-code-language="Rust"><pre><span></span><code><span class="cp">#[allow(unused_doc_comments)]</span><span class="w"></span>
<span class="sd">/// A doc comment</span>
</code></pre></div>

<p>really looks like it should be allowing that doc comment</p>



<a name="214333668"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/Doc%20comments%20on%20nested%20items/near/214333668" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Joshua Nelson <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/Doc.20comments.20on.20nested.20items.html#214333668">(Oct 23 2020 at 16:18)</a>:</h4>
<p>I was actually suggesting that we <em>always</em> make <code>allow</code> apply to the attributes</p>



<a name="214333684"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/Doc%20comments%20on%20nested%20items/near/214333684" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Joshua Nelson <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/Doc.20comments.20on.20nested.20items.html#214333684">(Oct 23 2020 at 16:18)</a>:</h4>
<p>not special case <code>unused_doc_comments</code></p>



<a name="214333692"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/Doc%20comments%20on%20nested%20items/near/214333692" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Aaron Hill <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/Doc.20comments.20on.20nested.20items.html#214333692">(Oct 23 2020 at 16:18)</a>:</h4>
<p>hmm</p>



<a name="214333702"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/Doc%20comments%20on%20nested%20items/near/214333702" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Aaron Hill <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/Doc.20comments.20on.20nested.20items.html#214333702">(Oct 23 2020 at 16:18)</a>:</h4>
<p>are there other attributes that make sense when applied to attributes</p>



<a name="214333742"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/Doc%20comments%20on%20nested%20items/near/214333742" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Aaron Hill <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/Doc.20comments.20on.20nested.20items.html#214333742">(Oct 23 2020 at 16:19)</a>:</h4>
<p>I guess there's 'unknown lint'</p>



<a name="214333920"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/Doc%20comments%20on%20nested%20items/near/214333920" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Aaron Hill <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/Doc.20comments.20on.20nested.20items.html#214333920">(Oct 23 2020 at 16:20)</a>:</h4>
<p>huh - it looks like that already has the expected behavior</p>



<a name="214333966"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/Doc%20comments%20on%20nested%20items/near/214333966" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Aaron Hill <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/Doc.20comments.20on.20nested.20items.html#214333966">(Oct 23 2020 at 16:21)</a>:</h4>
<p>This doesn't warn:</p>
<div class="codehilite" data-code-language="Rust"><pre><span></span><code><span class="w">    </span><span class="cp">#[allow(unknown_lints)]</span><span class="w"></span>
<span class="w">    </span><span class="cp">#[allow(something)]</span><span class="w"></span>
<span class="w">    </span><span class="kd">let</span><span class="w"> </span><span class="n">a</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">1</span><span class="p">;</span><span class="w"></span>
</code></pre></div>



<a name="214334029"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/Doc%20comments%20on%20nested%20items/near/214334029" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Aaron Hill <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/Doc.20comments.20on.20nested.20items.html#214334029">(Oct 23 2020 at 16:21)</a>:</h4>
<p>but it does warn if you swap the order:</p>
<div class="codehilite" data-code-language="Rust"><pre><span></span><code><span class="w">    </span><span class="cp">#[allow(something)]</span><span class="w"></span>
<span class="w">    </span><span class="cp">#[allow(unknown_lints)]</span><span class="w"></span>
<span class="w">    </span><span class="kd">let</span><span class="w"> </span><span class="n">a</span><span class="w"> </span><span class="o">=</span><span class="w"> </span><span class="mi">1</span><span class="p">;</span><span class="w"></span>
</code></pre></div>



<a name="214334048"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/Doc%20comments%20on%20nested%20items/near/214334048" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Aaron Hill <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/Doc.20comments.20on.20nested.20items.html#214334048">(Oct 23 2020 at 16:22)</a>:</h4>
<p>so, I guess we already have some form of 'attributes on attributes' (semantically, not syntactically)</p>



<a name="214334246"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/Doc%20comments%20on%20nested%20items/near/214334246" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Aaron Hill <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/Doc.20comments.20on.20nested.20items.html#214334246">(Oct 23 2020 at 16:23)</a>:</h4>
<p>I don't know if that's a bug, or a behavior we want to extend to unused_doc_comments</p>



<a name="214336021"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/Doc%20comments%20on%20nested%20items/near/214336021" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Joshua Nelson <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/Doc.20comments.20on.20nested.20items.html#214336021">(Oct 23 2020 at 16:37)</a>:</h4>
<p>personally I'd like to extend it</p>



<a name="214350562"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/Doc%20comments%20on%20nested%20items/near/214350562" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Aaron Hill <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/Doc.20comments.20on.20nested.20items.html#214350562">(Oct 23 2020 at 18:39)</a>:</h4>
<p>To make things even more confusing, <code>#[allow(unused_attributes)]</code> applies to sibiling attributes in any order</p>



<a name="214350622"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/Doc%20comments%20on%20nested%20items/near/214350622" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Aaron Hill <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/Doc.20comments.20on.20nested.20items.html#214350622">(Oct 23 2020 at 18:39)</a>:</h4>
<div class="codehilite" data-code-language="Rust"><pre><span></span><code><span class="k">trait</span><span class="w"> </span><span class="n">Foo</span><span class="w"> </span><span class="p">{</span><span class="w"></span>
<span class="w">    </span><span class="cp">#[allow(unused_attributes)]</span><span class="w"> </span><span class="cp">#[inline]</span><span class="w"> </span><span class="k">fn</span> <span class="nf">first</span><span class="p">();</span><span class="w"></span>
<span class="w">    </span><span class="cp">#[inline]</span><span class="w"> </span><span class="cp">#[allow(unused_attributes)]</span><span class="w"> </span><span class="k">fn</span> <span class="nf">second</span><span class="p">();</span><span class="w"></span>
<span class="w">    </span><span class="cp">#[inline]</span><span class="w"> </span><span class="k">fn</span> <span class="nf">third</span><span class="p">();</span><span class="w"></span>
<span class="p">}</span><span class="w"></span>
</code></pre></div>

<p>only the last function produces a warning</p>



<a name="214363327"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/Doc%20comments%20on%20nested%20items/near/214363327" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Aaron Hill <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/Doc.20comments.20on.20nested.20items.html#214363327">(Oct 23 2020 at 20:39)</a>:</h4>
<p>It turns out that this was caused by an inconsistency in how some of the lint visitors handle statements</p>



<a name="214363416"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/Doc%20comments%20on%20nested%20items/near/214363416" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Aaron Hill <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/Doc.20comments.20on.20nested.20items.html#214363416">(Oct 23 2020 at 20:40)</a>:</h4>
<p>The any-order behavior in the above snippet looks like the behavior we want for <code>#[allow(unused_doc_comments)]</code> as well</p>



<a name="214367371"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/Doc%20comments%20on%20nested%20items/near/214367371" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Aaron Hill <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/Doc.20comments.20on.20nested.20items.html#214367371">(Oct 23 2020 at 21:17)</a>:</h4>
<p>Opened <a href="https://github.com/rust-lang/rust/pull/78306">https://github.com/rust-lang/rust/pull/78306</a> to fix this</p>



<a name="214429223"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/Doc%20comments%20on%20nested%20items/near/214429223" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Daniel Henry-Mantilla <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/Doc.20comments.20on.20nested.20items.html#214429223">(Oct 24 2020 at 13:56)</a>:</h4>
<p>FWIW, I find doc-comments to be useful besides <code>rustdoc</code>-rendering. If <code>mod private { /** doc-comment */ pub fn __ () {} }</code> does not fire a warning, then neither should <code>fn private () { /** doc-comment */ pub fn __ () {} }</code>. I like the way these kind of comments "have direction" in that they are an attribute applied to the item below.<br>
So, <em>personally</em>, it would bother me if these kind of things started to be linted. So, if that were the case, there should, at least. be a dedicated special lint. Otherwise I _know_ I'd simply end up slapping <code>#![allow(unused_doc_comments)]</code> at the root of my crates <span aria-label="grimacing" class="emoji emoji-1f62c" role="img" title="grimacing">:grimacing:</span></p>



<a name="214435706"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/Doc%20comments%20on%20nested%20items/near/214435706" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Joshua Nelson <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/Doc.20comments.20on.20nested.20items.html#214435706">(Oct 24 2020 at 16:20)</a>:</h4>
<p>I guess I'm a little confused - when would this warn that you <em>want</em> to know about it? What lint would we be splitting out?</p>



<a name="214435760"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/Doc%20comments%20on%20nested%20items/near/214435760" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Joshua Nelson <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/Doc.20comments.20on.20nested.20items.html#214435760">(Oct 24 2020 at 16:20)</a>:</h4>
<p>I'm fine with making this allow by default FWIW</p>



<a name="214436427"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/Doc%20comments%20on%20nested%20items/near/214436427" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Aaron Hill <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/Doc.20comments.20on.20nested.20items.html#214436427">(Oct 24 2020 at 16:34)</a>:</h4>
<p><span class="user-mention" data-user-id="232545">@Joshua Nelson</span> Are you referring to my comment on the pull request? I was just splitting out internal rustc changes that have nothing to do with the lint</p>



<a name="214436434"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/Doc%20comments%20on%20nested%20items/near/214436434" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Aaron Hill <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/Doc.20comments.20on.20nested.20items.html#214436434">(Oct 24 2020 at 16:34)</a>:</h4>
<p>those changes are what exposed this behavior in the first place</p>



<a name="214436525"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/Doc%20comments%20on%20nested%20items/near/214436525" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Joshua Nelson <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/Doc.20comments.20on.20nested.20items.html#214436525">(Oct 24 2020 at 16:36)</a>:</h4>
<p><span class="user-mention" data-user-id="125294">@Aaron Hill</span> I'm referring to <span class="user-mention" data-user-id="232018">@Daniel Henry-Mantilla</span> 's comment:</p>
<blockquote>
<p>there should, at least. be a dedicated special lint. Otherwise I _know_ I'd simply end up slapping #![allow(unused_doc_comments)] at the root of my crates</p>
</blockquote>



<a name="214436532"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/Doc%20comments%20on%20nested%20items/near/214436532" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Joshua Nelson <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/Doc.20comments.20on.20nested.20items.html#214436532">(Oct 24 2020 at 16:36)</a>:</h4>
<p>I'm asking if we don't lint on statements what <em>would</em> be linted</p>



<a name="214436619"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/Doc%20comments%20on%20nested%20items/near/214436619" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Joshua Nelson <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/Doc.20comments.20on.20nested.20items.html#214436619">(Oct 24 2020 at 16:38)</a>:</h4>
<blockquote>
<p>If <code>mod private { /** doc-comment */ pub fn __ () {} }</code> does not fire a warning, then neither should <code>fn private () { /** doc-comment */ pub fn __ () {} }</code>. </p>
</blockquote>
<p>FWIW I don't like that <code>mod private</code> silences all lints inside it either, that exposes rustdoc internals a little. <code>Strip</code> should only affect the rendered docs IMO, not the warnings themselves.</p>



<a name="214436910"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/Doc%20comments%20on%20nested%20items/near/214436910" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Daniel Henry-Mantilla <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/Doc.20comments.20on.20nested.20items.html#214436910">(Oct 24 2020 at 16:44)</a>:</h4>
<p>I see, then I had interpreted <code>unused_doc_comments</code> differently (as one warning against docstrings on <em>statements</em>). If private items get linted, then items inside non-type-namespace scopes should get linted too <span aria-label="+1" class="emoji emoji-1f44d" role="img" title="+1">:+1:</span></p>



<a name="214436946"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/Doc%20comments%20on%20nested%20items/near/214436946" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Joshua Nelson <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/Doc.20comments.20on.20nested.20items.html#214436946">(Oct 24 2020 at 16:45)</a>:</h4>
<p>sorry - I was talking about the world I <em>want</em> to see, not as it is. Currently <code>mod -&gt; pub fn</code> does not lint, because the private module is completely stripped.</p>



<a name="214436998"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/Doc%20comments%20on%20nested%20items/near/214436998" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Joshua Nelson <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/Doc.20comments.20on.20nested.20items.html#214436998">(Oct 24 2020 at 16:46)</a>:</h4>
<p>I'm still not sure what <code>unused_doc_comments</code> <em>does</em> without the changes in <a href="https://github.com/rust-lang/rust/pull/78306">https://github.com/rust-lang/rust/pull/78306</a>, though.</p>



<a name="214437316"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/Doc%20comments%20on%20nested%20items/near/214437316" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Daniel Henry-Mantilla <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/Doc.20comments.20on.20nested.20items.html#214437316">(Oct 24 2020 at 16:52)</a>:</h4>
<p>What I mean is that after consideration, the world you want to see for that attribute makes more sense than mine <span aria-label="big smile" class="emoji emoji-1f604" role="img" title="big smile">:big_smile:</span></p>



<a name="214463154"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/Doc%20comments%20on%20nested%20items/near/214463154" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> scottmcm <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/Doc.20comments.20on.20nested.20items.html#214463154">(Oct 25 2020 at 02:29)</a>:</h4>
<p><span class="user-mention silent" data-user-id="232018">Daniel Henry-Mantilla</span> <a href="#narrow/stream/131828-t-compiler/topic/Doc.20comments.20on.20nested.20items/near/214429223">said</a>:</p>
<blockquote>
<p>If <code>mod private { /** doc-comment */ pub fn __ () {} }</code> does not fire a warning</p>
</blockquote>
<p>But you can skip the <a href="https://doc.rust-lang.org/rustdoc/passes.html#strip-private">https://doc.rust-lang.org/rustdoc/passes.html#strip-private</a> pass and get comments for that one.  (Which is handy in local.)</p>



<a name="214467744"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/Doc%20comments%20on%20nested%20items/near/214467744" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Daniel Henry-Mantilla <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/Doc.20comments.20on.20nested.20items.html#214467744">(Oct 25 2020 at 04:28)</a>:</h4>
<p>I never thought of customizing the passes themselves, interesting; I personally use <code>--document-private-items</code> and the yet unstable <code>--document-hidden-items</code>. From a recent shell history:</p>
<div class="codehilite" data-code-language="Bash"><pre><span></span><code><span class="nv">RUSTDOCFLAGS</span><span class="o">=</span><span class="s1">'-Zunstable-options --document-hidden-items'</span> <span class="nv">RUSTC_BOOTSTRAP</span><span class="o">=</span><span class="m">1</span> <span class="se">\</span>
cargo doc --document-private-items --open
</code></pre></div>



<a name="214470208"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/Doc%20comments%20on%20nested%20items/near/214470208" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Joshua Nelson <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/Doc.20comments.20on.20nested.20items.html#214470208">(Oct 25 2020 at 05:28)</a>:</h4>
<blockquote>
<p>RUSTC_BOOTSTRAP=1</p>
</blockquote>
<p><span aria-label="cry" class="emoji emoji-1f622" role="img" title="cry">:cry:</span></p>



<a name="214470229"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/Doc%20comments%20on%20nested%20items/near/214470229" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> Joshua Nelson <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/Doc.20comments.20on.20nested.20items.html#214470229">(Oct 25 2020 at 05:29)</a>:</h4>
<p>Also you can get better caching with <code>cargo rustdoc -- -Z unstable-options ..
</code> which doesn't have to recompile things when you change RUSTFLAGS</p>



<a name="214526066"></a>
<h4><a href="https://rust-lang.zulipchat.com#narrow/stream/131828-t-compiler/topic/Doc%20comments%20on%20nested%20items/near/214526066" class="zl"><img src="https://rust-lang.github.io/zulip_archive/assets/img/zulip.svg" alt="view this post on Zulip" style="width:20px;height:20px;"></a> scottmcm <a href="https://rust-lang.github.io/zulip_archive/stream/131828-t-compiler/topic/Doc.20comments.20on.20nested.20items.html#214526066">(Oct 26 2020 at 02:15)</a>:</h4>
<p><span class="user-mention" data-user-id="232018">@Daniel Henry-Mantilla</span> Ah, I thought there was a flag for that, but couldn't find it :P  <code>--document-private-items</code> is definitely the way to go.</p>



<hr><p>Last updated: Aug 07 2021 at 22:04 UTC</p>
</html>